CRDT-MCP AI Agent 동시 파일 편집 시스템

1. 프로젝트 개요

무엇을 만드는가?

CRDT(Conflict-free Replicated Data Types)를 활용하여 여러 AI agent(Claude Code 등)가 같은 파일을 동시에 안전하게 편집할 수 있는 MCP(Model Context Protocol) 서버.

왜 만드는가?

현재 문제점:

• 현존하는 AI 코딩 도구(Claude Code, Cursor, Copilot 등)는 multi-agent가 같은 파일을 동시에 편집하면 last-write-wins 문제가 발생
• Agent A의 수정을 Agent B가 덮어쓰는 데이터 손실 위험
• 현재 업계 표준은 "파일 단위로 작업 분리" → 근본적 해결이 아닌 회피
• 단일 agent 순차 작업은 병렬 작업 대비 비효율적

해결 방안:

• CRDT를 통해 동시 편집 시 자동 충돌 해결
• MCP 서버로 제공하여 Claude Code 등 AI 도구에 플러그인 형태로 연결
• Agent별 편집 operation을 실시간 병합하여 일관된 파일 상태 유지

2. 시스템 아키텍처

전체 구조

┌──────────────┐     ┌──────────────┐
│ Claude Code  │     │ Claude Code  │
│   Agent A    │     │   Agent B    │
└──────┬───────┘     └──────┬───────┘
       │  MCP (SSE/HTTP)    │
       └────────┬───────────┘
                │
       ┌────────▼────────┐
       │   MCP Server    │
       │  (CRDT Engine)  │
       │                 │
       │  - Yjs Doc      │
       │  - File I/O     │
       │  - Conflict     │
       │    Detection    │
       └────────┬────────┘
                │
          ┌─────▼─────┐
          │ File System│
          └───────────┘

컴포넌트 설명

MCP Transport 방식

SSE (Server-Sent Events) 방식 채택:

• MCP 서버를 하나 띄워두고, 여러 Claude Code 인스턴스가 같은 서버에 접속
• 별도 백엔드 불필요 — 로컬에서 도는 하나의 프로세스
• Claude Code 설정:

{
  "mcpServers": {
    "crdt-editor": {
      "url": "http://localhost:3000/sse"
    }
  }
}

3. MCP Tool 설계

MCP 서버가 AI agent에게 제공하는 도구:

`crdt_open`

• 설명: 파일을 CRDT 문서로 로드 (이미 열려있으면 기존 세션에 합류)
• 입력: { file_path: string }
• 출력: { session_id: string, content: string, active_agents: number }

`crdt_read`

• 설명: 현재 CRDT 문서 상태 읽기
• 입력: { file_path: string }
• 출력: { content: string, version: number }

`crdt_edit`

• 설명: 파일 편집 (삽입/삭제/교체)
• 입력: { file_path: string, operations: [{ type: "insert"|"delete"|"replace", position: number, content?: string, length?: number }] }
• 출력: { success: boolean, content: string, version: number }

`crdt_close`

• 설명: 편집 세션 종료 및 파일 저장
• 입력: { file_path: string }
• 출력: { success: boolean }

`crdt_status`

• 설명: 현재 세션 상태 조회 (활성 agent 수, 최근 변경 등)
• 입력: { file_path: string }
• 출력: { active_agents: number, last_modified: string, edit_history: [...] }

4. 차별화 기능 (캡스톤 가산점)

4-1. 의미적 충돌 감지

• CRDT는 텍스트 레벨 충돌만 해결
• 예: Agent A가 함수 삭제 + Agent B가 해당 함수 호출 코드 추가 → 텍스트는 병합되지만 코드는 깨짐
• AST 파싱을 통해 이런 논리적 충돌을 감지하고 agent에게 경고

4-2. 편집 히스토리 시각화

• 기존 웹 에디터를 확장하여 agent별 편집 내역을 색상으로 구분
• 타임라인 형태로 "누가 언제 어디를 수정했는지" 표시

5. 최종 데모 시나리오

데모 화면 구성

┌─────────────────────────────────────────────────────┐
│                                                     │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  Terminal A  │  │  Web Viewer  │  │ Terminal B │  │
│  │  (Agent A)  │  │  (실시간 뷰) │  │ (Agent B)  │  │
│  │             │  │              │  │            │  │
│  │  Claude     │  │  편집 내용이 │  │  Claude    │  │
│  │  Code       │  │  실시간으로  │  │  Code      │  │
│  │             │  │  합쳐지는    │  │            │  │
│  │  "로그인    │  │  모습이      │  │  "회원가입 │  │
│  │   기능      │  │  보임        │  │   기능     │  │
│  │   추가해줘" │  │              │  │   추가해줘"│  │
│  │             │  │  Agent A 색  │  │            │  │
│  │             │  │  Agent B 색  │  │            │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
│                                                     │
└─────────────────────────────────────────────────────┘

데모 시나리오

1. 서버 시작: node server.js → MCP 서버 + 웹 대시보드 실행
2. Agent A 접속: Claude Code 터미널에서 crdt_open("app.js") → 세션 합류
3. Agent B 접속: 다른 Claude Code 터미널에서 같은 파일 오픈 → 동시 접속 확인
4. 동시 편집:
   • Agent A에게: "이 파일에 로그인 기능 추가해줘"
   • Agent B에게: "이 파일에 회원가입 기능 추가해줘"
5. 실시간 병합: 가운데 웹 뷰어에서 두 agent의 편집이 실시간으로 합쳐지는 모습 시연
6. 결과 확인: 최종 파일에 두 기능이 충돌 없이 공존, 실행하여 정상 동작 확인

데모 포인트

• "동시에 같은 파일을 편집해도 서로의 작업이 사라지지 않는다"
• "CRDT가 자동으로 병합하여 일관된 결과를 만들어낸다"
• "기존 도구에서는 불가능한 병렬 작업이 가능해진다"

6. 기술 스택 및 필요 사항

기술 스택

필요 사항

• Node.js 18+ 설치
• MCP SDK 설치 (@modelcontextprotocol/sdk)
• Claude Code Pro 계정 2개 (또는 동일 계정으로 터미널 2개)
• 데모용 샘플 프로젝트 파일 준비

프로젝트 구조 (예상)

crdt/
├── server.js              # MCP 서버 (SSE transport)
├── crdt-engine.js         # Yjs CRDT 엔진 래퍼
├── file-sync.js           # CRDT ↔ 파일시스템 동기화
├── conflict-detector.js   # 의미적 충돌 감지 (선택)
├── public/
│   └── index.html         # 실시간 시각화 대시보드
├── package.json
└── PROJECT.md             # 이 문서